Beginning a Java Runtime Session

On the Mac OS platform, the Java runtime session is defined by the JMSessionRef object. To instantiate this object, you must call the function JMOpenSession. Listing 1-1 gives an example of creating a session.

The instantiated JMSessionRef object is referenced by the value of theSession . Other JManager functions require you to pass this value to identify the session. (You can create more than one instantiation of the Java runtime environment if you wish.) Note that the JMSessionCallbacks structure you pass contains a field indicating the version of JManager you are using in your program. You should always set this value to kJMVersion . Setting this value prevents your program from accessing older (possibly incompatible) JManager functions.

The text encoding you specify when calling JMOpenSession (kTextEncodingMacRoman in this example) indicates the encoding used for any data sent to the designated standard output or standard error.

Session and Security Options

When calling JMOpenSession , you pass two parameters that indicate the desired session options, and whether you want to use the code verifier.

The session options parameter is actually a mask that allows you to select various options, such as the following:

Whether the Java session can use temporary memory in addition to application heap memory. The default uses application heap memory only.
Whether to use the Just In Time (JIT) compiler. The default enables the compiler.
Whether to allow debugging. The default disables the debugger.
Whether to use preferences determined by InternetConfig. The default uses InternetConfig settings.
Whether to inhibit class unloading (that is, to prevent garbage collection of classes that are not being used). The default allows class unloading.

The example in Listing 1 passes eJManager2Defaults , which selects all the default settings. See Runtime Session Options for a list of the available options.

The code verifier parameter (set to eCheckRemoteCode in Listing 1) specifies whether you want the code verifier to check the Java code before attempting to execute it. The code verifier analyzes the code to make sure that it is valid Java code and that it does not attempt any illegal or questionable actions (such as pointer arithmetic) that could give the code access to the Mac OS runtime environment. Typically you should use the code verifier if you plan to receive Java code from an untrustworthy source (such as over a network). See Security Level Indicators for the available options.

After calling JMOpenSession , you can read or modify the code verifier setting by calling the functions JMGetVerifyMode or JMSetVerifyMode respectively.

Callbacks

The data structure you must pass to the JMOpenSession function is a set of callback functions to handle console input and output, calls to exit from a Java application, low memory conditions, and URL authentication.

The standard output, standard error, and standard input callbacks all deal with communications with the command line console. For example, you could specify a function that would receive and parse text sent to the standard output. Since the Mac OS runtime environment does not have a command line, these callbacks are often unused and set to nil . (By default, any text sent to standard output or standard error is redirected to a file.) For information about the form of these functions, see MyStandardOutput, MyStandardError, and MyStandardIn.
The exit handler handles the case where the Java application quits (by calling java.lang.System.exit ). Your callback can dispose of the applet or session as it sees fit, or it can simply allow the System.exit call to execute normally. For more information about the form of the exit handler, see MyExit.
The URL authentication handler is called in cases where the user must enter a name and password to gain access to a URL. The handler should prompt the user for the proper information and pass it back to the Java program, which then decides whether the information is valid. For more information about the form of the authentication handler, see MyAuthenticate.
The low memory handler is called when the Java runtime session runs low on memory. For more information about the form of the low memory handler, see MyLowMem.

For more information about the session callback structure, see Session Callbacks Structure.